<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>DB-&gt;associate_foreign()</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB C API Reference" />
    <link rel="up" href="db.html" title="Chapter 2.  The DB Handle" />
    <link rel="prev" href="dbassociate.html" title="DB-&gt;associate()" />
    <link rel="next" href="dbclose.html" title="DB-&gt;close()" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">DB-&gt;associate_foreign()</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="dbassociate.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. 
                The DB Handle
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="dbclose.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="dbassociate_foreign"></a>DB-&gt;associate_foreign()</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">#include &lt;db.h&gt;

int
DB-&gt;associate_foreign(DB *foreign, DB *secondary,,
   int (*callback)(DB *secondary,
   const DBT *key, DBT *data, const DBT *foreignkey, int *changed), 
   u_int32_t flags);  </pre>
      <p>
        The <code class="methodname">DB-&gt;associate_foreign()</code> function is used to declare one database a
        foreign constraint for a secondary database.  The 
        <a class="link" href="db.html" title="Chapter 2.  The DB Handle">DB</a> handle that you call the
        <code class="methodname">associate_foreign()</code> method from is the foreign
        database.
    </p>
      <p>
        After a foreign database has been "associated" with a secondary
        database, all keys inserted into the secondary must exist in the 
     foreign database.  Attempting to add a record with a foreign key
     that does not exist in the foreign database will cause the put
     method to fail and return <code class="literal">DB_FOREIGN_CONFLICT</code>.
    </p>
      <p>
        Deletions in the foreign database affect the secondary in a manner
     defined by the flags parameter.  See 
        <a href="../../programmer_reference/am_foreign.html" class="olink">Foreign Indices</a> 
        in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information.
   </p>
      <p>
        The <code class="methodname">DB-&gt;associate_foreign()</code> <span>
            <span>
                  method returns a non-zero error value on failure and 0 on success.
            </span>
            
        </span>
   </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp49290208"></a>Parameters</h3>
            </div>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp49302368"></a>foreign</h4>
              </div>
            </div>
          </div>
          <p>
                         The <span class="bold"><strong>foreign</strong></span> parameter should be a
                         database handle for the foreign database.
                    </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp49305584"></a>secondary</h4>
              </div>
            </div>
          </div>
          <p>
                         The <span class="bold"><strong>secondary</strong></span> parameter should be an
                         open database handle of a database that contains a secondary index who's
                         keys also exist in the <span class="bold"><strong>foreign</strong></span> database.  
                    </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp49229248"></a>callback</h4>
              </div>
            </div>
          </div>
          <p>
                         The <span class="bold"><strong>callback</strong></span> parameter is a callback
                         function that nullifies the foreign key portion of a data <a class="link" href="dbt.html" title="Chapter 4.  The DBT Handle">DBT</a>.
                    </p>
          <p>
                         The callback parameter must be NULL if either DB_FOREIGN_ABORT or DB_FOREIGN_CASCADE is set.
                    </p>
          <p>
                        The callback takes four arguments:
                    </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                               <code class="literal">secondary</code>
                           </p>
                <p>
                               The <span class="bold"><strong>secondary</strong></span> parameter is the
                               database handle for the secondary.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">key</code>
                           </p>
                <p>
                                   The <span class="bold"><strong>key</strong></span> parameter is a 
                                   <a class="link" href="dbt.html" title="Chapter 4.  The DBT Handle">DBT</a>  referencing the primary key.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">data</code>
                           </p>
                <p>
                                   The <span class="bold"><strong>data</strong></span> parameter is a 
                                   <a class="link" href="dbt.html" title="Chapter 4.  The DBT Handle">DBT</a>  referencing the primary data
                                   item to be updated.
                           </p>
              </li>
              <li>
                <p>
                               <code class="literal">foreignkey</code>
                           </p>
                <p>
                               The <span class="bold"><strong>foreignkey</strong></span> parameter is a
                               <a class="link" href="dbt.html" title="Chapter 4.  The DBT Handle">DBT</a>  referencing the foreign
                                key which is being deleted.
                           </p>
              </li>
              <li>
                <p>
                  <code class="literal">changed</code>
                           </p>
                <p>
                               The <span class="bold"><strong>changed</strong></span> parameter is a
                               pointer to a boolean value, indicated whether <span class="bold"><strong>data</strong></span>
                               has changed.
                           </p>
              </li>
            </ul>
          </div>
          <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
            <h3 class="title">Note</h3>
            <p>
           Berkeley DB is not re-entrant. Callback functions should not
           attempt to make library calls (for example, to release locks or
           close open handles). Re-entering Berkeley DB is not guaranteed
           to work correctly, and the results are undefined.
       </p>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp49360192"></a>flags</h4>
              </div>
            </div>
          </div>
          <p>
                         The <span class="bold"><strong>flags</strong></span> parameter must be set to 
                         one of the following values:
                    </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a id="associate_foreign_DB_FOREIGN_ABORT"></a>
                     <code class="literal">DB_FOREIGN_ABORT</code>
                   </p>
                <p>
              Abort the deletion of a key in the foreign database and return DB_FOREIGN_CONFLICT
              if that key exists in the secondary database.  The deletion should be protected by
              a transaction to ensure database integrity after the aborted delete.
            </p>
              </li>
              <li>
                <p><a id="associate_foreign_DB_FOREIGN_CASCADE"></a>
                     <code class="literal">DB_FOREIGN_CASCADE</code>
                   </p>
                <p>
              The deletion of a key in the foreign database will also delete that key from the
              secondary database (and the corresponding entry in the secondary's primary database.)
            </p>
              </li>
              <li>
                <p><a id="associate_foreign_DB_FOREIGN_NULLIFY"></a>
                     <code class="literal">DB_FOREIGN_NULLIFY</code>
                   </p>
                <p>
              The deletion of a key in the foreign database will call the nullification function
              passed to associate_foreign and update the secondary database with the changed data.
            </p>
              </li>
            </ul>
          </div>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp49300904"></a>Errors</h3>
            </div>
          </div>
        </div>
        <p>
                        The <code class="methodname">DB-&gt;associate_foreign()</code> <span>
            <span>
                 method may fail and return one of the following non-zero errors:
            </span>
            
        </span>
                   </p>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp49355232"></a>  DB_REP_HANDLE_DEAD</h4>
              </div>
            </div>
          </div>
          <p>
                When a client synchronizes with the master, it is possible for committed
                transactions to be rolled back. This invalidates all  the database and cursor
                handles opened in the replication environment. Once this occurs, an attempt to use
                such a handle will 
                
                return <code class="literal">DB_REP_HANDLE_DEAD</code>.
                The application will need to discard the handle and open a new one in order to
                continue processing.
            </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp49293408"></a>DB_REP_LOCKOUT</h4>
              </div>
            </div>
          </div>
          <p>
                The operation was blocked by client/master synchronization.
            </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp49348072"></a>EINVAL</h4>
              </div>
            </div>
          </div>
          <p>
                         If the foreign database handle is a secondary index; the foreign
                         database handle has been configured to allow duplicates; the foreign
                         database handle is a renumbering recno database; callback is
                         configured and DB_FOREIGN_NULLIFY is not; DB_FOREIGN_NULLIFY is
                         configured and callback is not.
                       </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp49259880"></a>Class</h3>
            </div>
          </div>
        </div>
        <p>
               <a class="link" href="db.html" title="Chapter 2.  The DB Handle">DB</a>  
           </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp49357296"></a>See Also</h3>
            </div>
          </div>
        </div>
        <p>
                    <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 
               </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="dbassociate.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="db.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="dbclose.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">DB-&gt;associate() </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> DB-&gt;close()</td>
        </tr>
      </table>
    </div>
  </body>
</html>
